<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><title>Fast way to find nearby points (distance to each Census block centroid near each site) — getblocksnearbyviaQuadTree • EJAM</title><!-- favicons --><link rel="icon" type="image/png" sizes="16x16" href="../favicon-16x16.png"><link rel="icon" type="image/png" sizes="32x32" href="../favicon-32x32.png"><link rel="apple-touch-icon" type="image/png" sizes="180x180" href="../apple-touch-icon.png"><link rel="apple-touch-icon" type="image/png" sizes="120x120" href="../apple-touch-icon-120x120.png"><link rel="apple-touch-icon" type="image/png" sizes="76x76" href="../apple-touch-icon-76x76.png"><link rel="apple-touch-icon" type="image/png" sizes="60x60" href="../apple-touch-icon-60x60.png"><script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><link href="../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet"><script src="../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><link href="../deps/font-awesome-6.4.2/css/all.min.css" rel="stylesheet"><link href="../deps/font-awesome-6.4.2/css/v4-shims.min.css" rel="stylesheet"><script src="../deps/headroom-0.11.0/headroom.min.js"></script><script src="../deps/headroom-0.11.0/jQuery.headroom.min.js"></script><script src="../deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js"></script><script src="../deps/clipboard.js-2.0.11/clipboard.min.js"></script><script src="../deps/search-1.0.0/autocomplete.jquery.min.js"></script><script src="../deps/search-1.0.0/fuse.min.js"></script><script src="../deps/search-1.0.0/mark.min.js"></script><!-- pkgdown --><script src="../pkgdown.js"></script><meta property="og:title" content="Fast way to find nearby points (distance to each Census block centroid near each site) — getblocksnearbyviaQuadTree"><meta name="description" content="This is what getblocksnearby() uses to do the work.
Given a set of points and a specified radius in miles,
this function quickly finds all the US Census blocks near each point.
This does the work actually supporting getblocksnearby()"><meta property="og:description" content="This is what getblocksnearby() uses to do the work.
Given a set of points and a specified radius in miles,
this function quickly finds all the US Census blocks near each point.
This does the work actually supporting getblocksnearby()"><meta property="og:image" content="https://usepa.github.io/EJAM/logo.svg"></head><body>
    <a href="#main" class="visually-hidden-focusable">Skip to contents</a>


    <nav class="navbar navbar-expand-lg fixed-top bg-light" data-bs-theme="light" aria-label="Site navigation"><div class="container">

    <a class="navbar-brand me-2" href="../index.html">EJAM</a>

    <small class="nav-text text-warning me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Released version">2.32.0</small>


    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>

    <div id="navbar" class="collapse navbar-collapse ms-3">
      <ul class="navbar-nav me-auto"><li class="active nav-item"><a class="nav-link" href="../reference/index.html">Reference</a></li>
<li class="nav-item dropdown">
  <button class="nav-link dropdown-toggle" type="button" id="dropdown-articles" data-bs-toggle="dropdown" aria-expanded="false" aria-haspopup="true">Articles</button>
  <ul class="dropdown-menu" aria-labelledby="dropdown-articles"><li><hr class="dropdown-divider"></li>
    <li><h6 class="dropdown-header" data-toc-skip>Overview for EJAM Users</h6></li>
    <li><a class="dropdown-item" href="../articles/0_whatis.html">What is EJAM</a></li>
    <li><a class="dropdown-item" href="../articles/0_webapp.html">Using EJAM</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><h6 class="dropdown-header" data-toc-skip>For analysts using R</h6></li>
    <li><a class="dropdown-item" href="../articles/1_installing.html">Installing the EJAM R package</a></li>
    <li><a class="dropdown-item" href="../articles/2_quickstart.html">Quick Start Guide</a></li>
    <li><a class="dropdown-item" href="../articles/3_analyzing.html">Basics of Using EJAM for Analysis in RStudio</a></li>
    <li><a class="dropdown-item" href="../articles/4_advanced.html">Advanced Features</a></li>
  </ul></li>
<li class="nav-item"><a class="nav-link" href="../news/index.html">Changelog</a></li>
      </ul><ul class="navbar-nav"><li class="nav-item"><form class="form-inline" role="search">
 <input class="form-control" type="search" name="search-input" id="search-input" autocomplete="off" aria-label="Search site" placeholder="Search for" data-search-index="../search.json"></form></li>
<li class="nav-item"><a class="external-link nav-link" href="https://github.com/USEPA/EJAM/" aria-label="GitHub"><span class="fa fab fa-github fa-lg"></span></a></li>
      </ul></div>


  </div>
</nav><div class="container template-reference-topic">
<div class="row">
  <main id="main" class="col-md-9"><div class="page-header">
      <img src="../logo.svg" class="logo" alt=""><h1>Fast way to find nearby points (distance to each Census block centroid near each site)</h1>
      <small class="dont-index">Source: <a href="https://github.com/USEPA/EJAM/blob/HEAD/R/getblocksnearbyviaQuadTree.R" class="external-link"><code>R/getblocksnearbyviaQuadTree.R</code></a></small>
      <div class="d-none name"><code>getblocksnearbyviaQuadTree.Rd</code></div>
    </div>

    <div class="ref-description section level2">
    <p>This is what <code><a href="getblocksnearby.html">getblocksnearby()</a></code> uses to do the work.
Given a set of points and a specified radius in miles,
this function quickly finds all the US Census blocks near each point.
This does the work actually supporting getblocksnearby()</p>
    </div>

    <div class="section level2">
    <h2 id="ref-usage">Usage<a class="anchor" aria-label="anchor" href="#ref-usage"></a></h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">getblocksnearbyviaQuadTree</span><span class="op">(</span></span>
<span>  <span class="va">sitepoints</span>,</span>
<span>  radius <span class="op">=</span> <span class="fl">3</span>,</span>
<span>  radius_donut_lower_edge <span class="op">=</span> <span class="fl">0</span>,</span>
<span>  maxradius <span class="op">=</span> <span class="fl">31.07</span>,</span>
<span>  avoidorphans <span class="op">=</span> <span class="cn">FALSE</span>,</span>
<span>  report_progress_every_n <span class="op">=</span> <span class="fl">500</span>,</span>
<span>  quiet <span class="op">=</span> <span class="cn">FALSE</span>,</span>
<span>  use_unadjusted_distance <span class="op">=</span> <span class="cn">FALSE</span>,</span>
<span>  retain_unadjusted_distance <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  <span class="va">quadtree</span>,</span>
<span>  updateProgress <span class="op">=</span> <span class="cn">NULL</span></span>
<span><span class="op">)</span></span></code></pre></div>
    </div>

    <div class="section level2">
    <h2 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#arguments"></a></h2>


<dl><dt id="arg-sitepoints">sitepoints<a class="anchor" aria-label="anchor" href="#arg-sitepoints"></a></dt>
<dd><p>data.table with columns lat, lon giving point locations of sites or facilities around which are circular buffers</p></dd>


<dt id="arg-radius">radius<a class="anchor" aria-label="anchor" href="#arg-radius"></a></dt>
<dd><p>in miles, defining circular buffer around a site point</p></dd>


<dt id="arg-radius-donut-lower-edge">radius_donut_lower_edge<a class="anchor" aria-label="anchor" href="#arg-radius-donut-lower-edge"></a></dt>
<dd><p>radius of lower edge of ring if analyzing ring not full circle</p></dd>


<dt id="arg-maxradius">maxradius<a class="anchor" aria-label="anchor" href="#arg-maxradius"></a></dt>
<dd><p>miles distance (max distance to check if not even 1 block point is within radius)</p></dd>


<dt id="arg-avoidorphans">avoidorphans<a class="anchor" aria-label="anchor" href="#arg-avoidorphans"></a></dt>
<dd><p>logical If TRUE, then where not even 1 BLOCK internal point is within radius of a SITE,
it keeps looking past radius, up to maxradius, to find nearest 1 BLOCK.
What EJScreen does in that case is report NA, right? So,
does EJAM really need to report stats on residents presumed to be within radius,
if no block centroid is within radius?
Best estimate might be to report indicators from nearest block centroid which is
probably almost always the one your site is sitting inside of,
but ideally would adjust total count to be a fraction of blockwt based on
what is area of circular buffer as fraction of area of block it is apparently inside of.
Setting this to TRUE can produce unexpected results, which will not match EJScreen numbers.</p>
<p>Note that if creating a proximity score, by contrast, you instead want to find nearest 1 SITE if none within radius of this BLOCK.</p></dd>


<dt id="arg-report-progress-every-n">report_progress_every_n<a class="anchor" aria-label="anchor" href="#arg-report-progress-every-n"></a></dt>
<dd><p>Reports progress to console after every n points,
mostly for testing, but a progress bar feature might be useful unless this is super fast.</p></dd>


<dt id="arg-quiet">quiet<a class="anchor" aria-label="anchor" href="#arg-quiet"></a></dt>
<dd><p>Optional. set to TRUE to avoid message about using getblock_diagnostics(),
which is relevant only if a user saved the output of this function.</p></dd>


<dt id="arg-use-unadjusted-distance">use_unadjusted_distance<a class="anchor" aria-label="anchor" href="#arg-use-unadjusted-distance"></a></dt>
<dd><p>logical, whether to find points within unadjusted distance</p></dd>


<dt id="arg-retain-unadjusted-distance">retain_unadjusted_distance<a class="anchor" aria-label="anchor" href="#arg-retain-unadjusted-distance"></a></dt>
<dd><p>set to FALSE to drop it and save memory/storage. If TRUE,
the distance_unadjusted column will save the actual distance of site to block internal point
– the distance column always represents distance to average resident in the block, which is
estimated by adjusting the site to block distance in cases where it is small relative to the
size of the block, to put a lower limit on it, which can result in a large estimate of distance
if the block is very large. See EJScreen documentation.</p></dd>


<dt id="arg-quadtree">quadtree<a class="anchor" aria-label="anchor" href="#arg-quadtree"></a></dt>
<dd><p>(a pointer to the large quadtree object)
created using indexblocks() which uses the SearchTree package.
Takes about 2-5 seconds to create this each time it is needed.
It can be automatically created when the package is attached via the .onAttach() function</p></dd>


<dt id="arg-updateprogress-">updateProgress, <a class="anchor" aria-label="anchor" href="#arg-updateprogress-"></a></dt>
<dd><p>optional function to update Shiny progress bar</p></dd>

</dl></div>
    <div class="section level2">
    <h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2>
    <p>For each point, it uses the specified search radius and finds the distance to
every block within the circle defined by the radius.
Each block is defined by its Census-provided internal point, by latitude and longitude.</p>
<p>Results are the sites2blocks table that would be used by doaggregate(),
with distance in miles as one output column of data.table.
Adjusts distance to avg resident in block when it is very small relative to block size,
the same way EJScreen adjusts distances in creating proximity scores.</p>
<p>Each point can be the location of a regulated facility or other type of site, and
the blocks are a high-resolution source of information about where
residents live.</p>
<p>Finding which blocks have their internal points in a circle provides
a way to quickly estimate what fraction of a block group is
inside the circular buffer more accurately and more quickly than
areal apportionment of block groups would provide.</p>
    </div>
    <div class="section level2">
    <h2 id="see-also">See also<a class="anchor" aria-label="anchor" href="#see-also"></a></h2>
    <div class="dont-index"><p><code><a href="ejamit.html">ejamit()</a></code> <code><a href="getblocksnearby.html">getblocksnearby()</a></code></p></div>
    </div>

    <div class="section level2">
    <h2 id="ref-examples">Examples<a class="anchor" aria-label="anchor" href="#ref-examples"></a></h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span>  <span class="co"># indexblocks() # if localtree not available yet, quadtree = localtree</span></span>
<span>  <span class="va">x</span> <span class="op">=</span> <span class="fu"><a href="getblocksnearby.html">getblocksnearby</a></span><span class="op">(</span><span class="va">testpoints_1000</span>, radius <span class="op">=</span> <span class="fl">3</span><span class="op">)</span></span></code></pre></div>
    </div>
  </main><aside class="col-md-3"><nav id="toc" aria-label="Table of contents"><h2>On this page</h2>
    </nav></aside></div>


    <footer><div class="pkgdown-footer-left">
  <p>US EPA 2024</p>
</div>

<div class="pkgdown-footer-right">
  <p>EJAM Version 2.32.0</p>
</div>

    </footer></div>





  </body></html>

